---
title: run
description: API reference for the `turbo run` command
---

import { Callout } from '#/components/callout';

Run tasks specified in `turbo.json`.

```bash title="Terminal"
turbo run [tasks] [options] [-- [args passed to tasks]]
```

- **[tasks]**: Turborepo can run one or many tasks at the same time. To run a task through `turbo`, it must be specified in `turbo.json`.
- **[options]**: Options are used to control the behavior of the `turbo run` command. Available flag options are described below.
- **[-- [args passed to tasks]]**: You may also pass arguments to the underlying scripts. Note that all arguments will be passed to all tasks.

<Callout type="good-to-know">
  `turbo run` is aliased to `turbo`. `turbo run build lint check-types` is the
  same as `turbo build lint check-types`. We recommend [using `turbo run` in CI
  pipelines](/repo/docs/crafting-your-repository/constructing-ci#use-turbo-run-in-ci)
  and `turbo` with [global `turbo`
  locally](/repo/docs/getting-started/installation#global-installation) for ease
  of use.
</Callout>

## Options

### `--cache-dir <path>`

Default: `.turbo/cache`

Specify the filesystem cache directory.

```bash title="Terminal"
turbo run build --cache-dir="./my-cache"
```

<Callout type="warn">
  Ensure the directory is in your `.gitignore` when changing it.
</Callout>

### `--concurrency <number | percentage>`

Default: `10`

Set/limit the maximum concurrency for task execution. Must be an integer greater than or equal to `1` or a percentage value like `50%`.

- Use `1` to force serial execution (one task at a time).
- Use `100%` to use all available logical processors.
- This option is ignored if the [`--parallel`](#--parallel) flag is also passed.

```bash title="Terminal"
turbo run build --concurrency=50%
turbo run test --concurrency=5
```

### `--continue`

Default: `false`

Continue with task execution in the presence of an error (e.g. non-zero exit code from a task).

When `--continue` is `true`, `turbo` will exit with the highest exit code value encountered during execution.

<Callout type="good-to-know">
  Specifying [the `--parallel` flag](#--parallel) will automatically set
  `--continue` to `true` unless explicitly set to `false`.
</Callout>

```bash title="Terminal"
turbo run build --continue
```

### `--cwd <path>`

Default: Directory of root `turbo.json`

Set the working directory of the command.

```bash title="Terminal"
turbo run build --cwd=./somewhere/else/in/your/repo
```

### `--dangerously-disable-package-manager-check`

Turborepo uses your repository's lockfile to determine caching behavior, [Package Graphs](https://turbo.build/repo/docs/core-concepts/internal-packages), and more. Because of this, we use [the `packageManager` field](https://nodejs.org/api/packages.html#packagemanager) to help you stabilize your Turborepo.

To help with incremental migration or in situations where you cannot use the `packageManager` field, you may use `--dangerously-disable-package-manager-check` to opt out of this check and assume the risks of unstable lockfiles producing unpredictable behavior. When disabled, Turborepo will attempt a best-effort discovery of the intended package manager meant for the repository.

<Callout type="info">
  You may also opt out of this check using [configuration in
  `turbo.json`](/repo/docs/reference/configuration#dangerouslydisablepacakgemanagercheck)
  or the
  [`TURBO_DANGEROUSLY_DISABLE_PACKAGE_MANAGER_CHECK`](/repo/docs/reference/system-environment-variables)
  environment variable for broader coverage.
</Callout>

### `--dry / --dry-run`

Instead of executing tasks, display details about the packages and tasks that would be run.

Specify `--dry=json` to get the output in JSON format.

Task details include useful information like (list is non-exhaustive):

| Field                        | Description                                                            |
| ---------------------------- | ---------------------------------------------------------------------- |
| `taskId`                     | ID for the task, in the format of `package-name#task-name`             |
| `task`                       | The name of the task to be executed                                    |
| `package`                    | The package in which to run the task                                   |
| `hash`                       | The hash of the task (used for caching)                                |
| `hashOfExternalDependencies` | The global hash                                                        |
| `command`                    | The command used to run the task                                       |
| `inputs`                     | List of file inputs considered for hashing                             |
| `outputs`                    | List of file outputs that were cached                                  |
| `dependencies`               | Tasks that must run **before** this task                               |
| `dependents`                 | Tasks that must run **after** this task                                |
| `environmentVariables`       | Lists of environment variables specified in `env` and `passThroughEnv` |

### `--env-mode <option>`

`type: string`

Controls the available environment variables in the task's runtime.

<Callout type="good-to-know">
  `PATH`, `SHELL`, and `SYSTEMROOT` are always available to the task.
</Callout>

| option                      | description                                                        |
| --------------------------- | ------------------------------------------------------------------ |
| [strict](#strict) (Default) | Only allow explicitly listed environment variables to be available |
| [loose](#loose)             | Allow **all** environment variables to be available                |

```bash title="Terminal"
turbo run build --env-mode=loose
```

#### `strict`

Only environment variables specified in the following keys are
available to the task:

- [`env`](/repo/docs/reference/configuration#env)
- [`passThroughEnv`](/repo/docs/reference/configuration#passthroughenv)
- [`globalEnv`](/repo/docs/reference/configuration#globalenv)
- [`globalPassThroughEnv`](/repo/docs/reference/configuration#globalpassthroughenv)

If Strict Mode is specified or inferred, **all** tasks are run in `strict` mode,
regardless of their configuration.

#### `loose`

All environment variables on the machine are made available to the task's runtime.

<Callout type="warn">
  This can be dangerous when environment variables are not accounted for in
  caching with the keys listed in `strict` above. You're much more likely to
  restore a version of your package with wrong environment variables from cache
  in `loose` mode.
</Callout>

### `--filter <string>`

Specify targets to execute from your repository's graph. Multiple filters can be combined to select distinct sets of targets.

Filters can be combined to create combinations of packages, directories, and git commits.

| Target type | Description                                                                                                                | Example                             |
| ----------- | -------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
| Package     | Select a package by its name in `package.json`.                                                                            | `turbo run build --filter=ui`       |
| Directory   | Specify directories to capture a list of packages to run tasks. **When used with other filters, must be wrapped in `{}`**. | `turbo run build --filter=./apps/*` |
| Git commits | Using Git specifiers, specify packages with source control changes. **Must be wrapped in `[]`**.                           | `turbo run build --filter=[HEAD^1]` |

<Callout type="good-to-know">`-F` is an alias for `--filter`.</Callout>

#### Microsyntaxes for filtering

- `!`: Negate targets from the selection.
- `...` using packages: Select all packages in the [Package Graph](/repo/docs/core-concepts/package-and-task-graph#package-graph) relative to the target. Using `...` **before** the package name will select **dependents** of the target while using `...` **after** the package name will select **dependencies** of the target.
- `...` using Git commits: Select a range using `[<from commit>]...[<to commit>]`.
- `^`: Omit the target from the selection when using `...`.

For in-depth discussion and practical use cases of filtering, visit [the Running Tasks page](/repo/docs/crafting-your-repository/running-tasks).

#### Advanced filtering examples

You can combine multiple filters to further refine your targets. Multiple filters are combined as a union, with negated filters removing packages from the result of the union.

```bash title="Terminal"
# Any packages in `apps` subdirectories that have changed since the last commit
turbo run build --filter={.apps/*}[HEAD^1]

# Any packages in `apps` subdirectories except ./apps/admin
turbo run build --filter=./apps/* --filter=!./apps/admin

# Run the build task for the docs and web packages
turbo run build --filter=docs --filter=web

# Build everything that depends on changes in branch 'my-feature'
turbo run build --filter=...[origin/my-feature]

# Build everything that depends on changes between two Git SHAs
turbo run build --filter=[a1b2c3d...e4f5g6h]

# Build '@acme/ui' if:
# - It or any of its dependencies have changed since the previous commit
turbo run build --filter=@acme/ui...[HEAD^1]

# Test each package that is:
# - In the '@acme' scope
# - Or, in the 'packages' directory
# - Or, changed since the previous commit
turbo run test --filter=@acme/*{./packages/*}[HEAD^1]
```

### `--force`

Ignore existing cached artifacts and re-execute all tasks.

<Callout type="good-to-know">
  `--force` will overwrite existing task caches.
</Callout>

```bash title="Terminal"
turbo run build --force
```

The same behavior can also be set via [the `TURBO_FORCE` environment variable](/repo/docs/reference/system-environment-variables).

### `--framework-inference`

Default: `true`

Specify whether or not to do [Framework Inference](/repo/docs/crafting-your-repository/using-environment-variables#framework-inference) for tasks.

When `false`, [automatic environment variable inclusion](/repo/docs/crafting-your-repository/using-environment-variables#framework-inference) is disabled.

```bash title="Terminal"
turbo run build --framework-inference=false
```

### `--global-deps <file glob>`

Specify glob of global filesystem dependencies to be hashed. Useful for `.env` and files in the root directory that impact multiple packages.

```bash title="Terminal"
turbo run build --global-deps=".env"
turbo run build --global-deps=".env.*" --global-deps=".eslintrc" --global-deps="jest.config.js"
```

<Callout type="info">
  We recommend specifying file globs that you'd like to include your hashes in
  [the `globalDependencies` key](/repo/docs/reference/configuration#globaldeps)
  in `turbo.json` to make sure they are always accounted for.
</Callout>

### `--graph <file type>`

Default: `jpg`

This command will generate an `svg`, `png`, `jpg`, `pdf`, `json`, `html`, or [other supported output formats](https://graphviz.org/doc/info/output.html) of the current task graph.

If [Graphviz](https://graphviz.org/) is not installed, or no filename is provided, this command prints the dot graph to `stdout`.

```bash title="Terminal"
turbo run build --graph
turbo run build test lint --graph=my-graph.svg
```

<Callout type="info">
  **Known Bug**: All possible task nodes will be added to the graph at the
  moment, even if that script does not actually exist in a given package. This
  has no impact on execution, but the graph may overstate the number of packages
  and tasks involved.
</Callout>

### `--log-order <option>`

Default: `auto`

Set the ordering for log output.

By default, `turbo` will use `grouped` logs in CI environments and `stream` logs everywhere else. This flag is not applicable when using [the terminal UI](https://turbo.build/repo/docs/reference/configuration#ui).

```bash title="Terminal"
turbo run build --log-order=stream
```

| Option    | Description                               |
| --------- | ----------------------------------------- |
| `stream`  | Show output as soon as it is available    |
| `grouped` | Group output by task                      |
| `auto`    | Turbo decides based on its own heuristics |

### `--log-prefix <option>`

Default: `auto`

Control the `<package>:<task>:` prefix for log lines produced when running tasks.

```bash title="Terminal"
turbo run dev --log-prefix=none
```

| Option   | Description                                 |
| -------- | ------------------------------------------- |
| `prefix` | Force prepending the prefix to logs         |
| `none`   | No prefixes                                 |
| `auto`   | `turbo` decides based on its own heuristics |

### `--no-cache`

Default `false`

Do not cache results of the task.

```bash title="Terminal"
turbo run dev --no-cache
```

### `--no-daemon`

Default: `false`

`turbo` can run a background process to pre-calculate values used for determining work that needs to be done. This standalone process (daemon) is an optimization, and not required for proper functioning of `turbo`.

Passing `--no-daemon` instructs `turbo` to avoid using or creating the standalone process.

### `--output-logs <option>`

Default: `full`

Set type of output logging, overriding [`outputLogs`](/repo/docs/reference/configuration#outputlogs) if it's defined in `turbo.json`.

```bash title="Terminal"
turbo run build --output-logs=errors-only
```

| Option        | Description                       |
| ------------- | --------------------------------- |
| `full`        | Displays all logs                 |
| `hash-only`   | Only show the hashes of the tasks |
| `new-only`    | Only show logs from cache misses  |
| `errors-only` | Only show logs from task failures |
| `none`        | Hides all task logs               |

### `--only`

Default: `false`

Restricts execution to include specified tasks only.

#### Example

Given this `turbo.json`:

```json title="./turbo.json"
{
  "$schema": "https://turbo.build/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"]
    },
    "test": {
      "dependsOn": ["^build"]
    }
  }
}
```

```bash title="Terminal"
turbo run test --only
```

The command will _only_ execute the `test` tasks in each package. It will not run `build`.

Additionally, `--only` will only run tasks in specified packages, excluding dependencies. For example, `turbo run build --filter=web --only`, will **only** run the `build` script in the `web` package.

### `--parallel`

Default: `false`

Run commands in parallel across packages, ignoring the task dependency graph.

```bash title="Terminal"
turbo run lint --parallel
turbo run dev --parallel
```

<Callout type="info">
  The `--parallel` flag is typically used for long-running "dev" or "watch"
  tasks that don't exit. Starting in `turbo@1.7`, we recommend configuring these
  tasks using [`persistent`](/repo/docs/reference/configuration#persistent)
  instead.
</Callout>

### `--preflight`

Only applicable when Remote Caching is configured. Enables sending a preflight request before every cache artifact and analytics request. The follow-up upload and download will follow redirects.

```bash title="Terminal"
turbo run build --preflight
```

The same behavior can also be set via the `TURBO_PREFLIGHT=true` system variable.

### `--profile`

Generates a trace of the run in Chrome Tracing format that you can use to analyze performance.

You must provide a verbosity flag (`-v`, `-vv`, or `-vvv`) with `--profile` to produce a trace.

```bash title="Terminal"
turbo run build --profile=profile.json -vvv
```

Profiles can be viewed in a tool like [Perfetto](https://ui.perfetto.dev/).

### `--remote-cache-timeout`

Default: `30`

Set the timeout for Remote Cache operations in seconds.

```bash title="Terminal"
turbo run build --remote-cache-timeout=60
```

### `--remote-only`

Default: `false`

Ignore the local filesystem cache for all tasks, using Remote Cache for reading and caching task outputs.

```bash title="Terminal"
turbo run build --remote-only
```

### `--summarize`

Generates a JSON file in `.turbo/runs` containing metadata about the run, including:

- Affected packages
- Executed tasks (including their timings and hashes)
- All the files included in the cached artifact

```bash title="Terminal"
turbo run build --summarize
```

This flag can be helpful for debugging to determine things like:

- How `turbo` interpreted your glob syntax for `inputs` and `outputs`
- What inputs changed between two task runs to produce a cache miss
- How task timings changed over time

### `--token`

A bearer token for Remote Caching. Useful for running in non-interactive shells in combination with the `--team` flag.

```bash title="Terminal"
turbo run build --team=my-team --token=xxxxxxxxxxxxxxxxx
```

This value can also be set using [the `TURBO_TOKEN` system variable](/repo/docs/reference/system-environment-variables). If both are present, the flag value will override the system variable.

<Callout type="good-to-know">
  If you are using [Vercel Remote
  Cache](https://vercel.com/docs/monorepos/remote-caching) and building your
  project on Vercel, you do not need to use this flag. This value will be
  automatically set for you.
</Callout>

### `--team`

The slug of the Remote Cache team. Useful for running in non-interactive shells in combination with the `--token` flag.

```bash title="Terminal"
turbo run build --team=my-team
turbo run build --team=my-team --token=xxxxxxxxxxxxxxxxx
```

### `--ui`

Specify the UI to use for output. Accepts `stream` or `tui`.

This value can also be set using [the `TURBO_TEAM` system variable](/repo/docs/reference/system-environment-variables). If both are present, the flag value will override the system variable.

### `--verbosity`

To specify log level, use `--verbosity=<num>` or `-v, -vv, -vvv`.

| Level | Flag value      | Shorthand |
| ----- | --------------- | --------- |
| Info  | `--verbosity=1` | `-v`      |
| Debug | `--verbosity=2` | `-vv`     |
| Trace | `--verbosity=3` | `-vvv`    |

```bash title="Terminal"
turbo run build --verbosity=2
turbo run build -vvv
```
